home *** CD-ROM | disk | FTP | other *** search
/ Grand Slam / GrandSlam volume 1.iso / 018 / far096.arj / FORMATS.DOC < prev    next >
Text File  |  1994-04-13  |  19KB  |  468 lines
  1.  
  2.      ╓─────────────────────────────────────────────────────────────╖
  3.      ║                                          ╓          ╖
  4.      ╟───  ╓────╖  ╖────╖  ╓────╖  ╖────╖  ╓────║  ╓────╖  ║  ╓────╖
  5.      ║     ╓─── ║  ║       ╓─── ║  ║    ║  ║    ║  ║    ║  ║  ║ ───╜
  6.      ║     ║    ║  ║       ║    ║  ║    ║  ║    ║  ║    ║  ║  ║    ║
  7.      ╜     ╙────╜  ╜       ╙────╜  ╜    ╙  ╙────╙  ╙────╜  ╙  ╙────╜
  8.      ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  9.                                                ──────══════ COMPOSER
  10.               ╓                      ╥
  11.               ║         ─╥─     ╖    ║      ╓──╖        ─╥─
  12.            ╓──║ ╥ ╓──╖ ╥ ║ ╓──╖ ║    ║ ╖──╖ ║─  ╥ ╖──╖ ╥ ║ ╖  ╓
  13.            ╙──╜ ╨ ╙──║ ╨ ╙ ╙──╙ ╙    ╙ ╜  ╙ ╙   ╨ ╜  ╙ ╨ ╙ ╙──╢
  14.                      ╜                                        ╜  93!
  15.      ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  16.  
  17.  
  18.  
  19.                        Format Specifications!!
  20.                           by Daniel Potter
  21.  
  22.  
  23. -----------------------------------------------------------------------------
  24.  
  25. Well, as you probably know, this is a pretty exciting program already. However,
  26. it would be nothing to a lot of people who would use it in their games, demos,
  27. etc, if I did not include the format specs. Besides that, I intend that this
  28. format, which although is CERTAINLY not the most efficient (basically a dump
  29. of the internals of the composer's editing mem), they will perhaps serve as
  30. a standard 16 channel format, with ease of use on the level of a MOD. Remember
  31. that this format is for EDITING purposes (storing EVERYTHING you're working on)
  32. so it may include information not completely neccessary. You can even see into
  33. the last moments of creation of the song through some of these variables :)
  34. You may process this info as you see fit, such as the scrolltext, which is not
  35. even supported in the current version of the composer. You could simply display
  36. it on the screen, or you could be creative, and have a scroller at the top of
  37. the screen while it's playing (that's the idea, for things like musicdisks).
  38.  
  39.  
  40.              Farandole .FAR file (16 channel tracker) format
  41.              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  42.  
  43. Header
  44.  
  45. Note that with the way the file magic(s) are set up, you can see the name of
  46. the song by TYPEing it from DOS. For example, if the song name was
  47. "StarLit MoonRise" then you would see when you typed it out:
  48.  
  49. FAR■StarLit MoonRise
  50.  
  51. In case you're teeming over with all the anxiety of all the wasted information
  52. in the header, just think back to the last time you saw a tracker that saved
  53. every info about what you were doing last. Think of it as a project file in
  54. Borland C.
  55.  
  56. len      desc
  57. -----------------------------------------------------------------------------
  58.  4       "FAR■" (file magic)
  59.  40      Song name
  60.  3       13,10,26 (bytes) (end of file chars)
  61.  2       Remaining length of header in bytes
  62.  1       Version number, major/minor upper/lower nybbles (0x10)
  63.  16      Channel ON/OFF map
  64.  1       Current editing octave
  65.  1       Current editing voice
  66.  1       Current editing row
  67.  1       Current editing pattern
  68.  1       Current editing order
  69.  1       Current editing sample
  70.  1       Current editing volume
  71.  1       Current top of screen display (top row visible)
  72.  1       Current editing area of the screen (0=sample,1=pattern,2=order)
  73.  1       Current tempo (default tempo)
  74.  16      Panning map, from 0-F for each channel
  75.  1       MarkTop (block)
  76.  1       MarkBot (block)
  77.  1       Grid granularity (default 4)
  78.  1       Edit Mode
  79.  2       Song text length
  80.  (above) Song text of length STLen (field above)
  81.  256     Order bytes
  82.  1       Number of patterns stored in the file
  83.  1       Length of order used
  84.  1       LoopTo location
  85.  2*256   Length in bytes of each pattern - Determine number of rows stored
  86.          for this pattern with this formula:
  87.  
  88.          Rows=((PatSize-2)/(16*4))
  89.  
  90.          The -2 will be explained below.
  91.  
  92.  If the file is of a newer format than this one, then there might be extra
  93.  stuff down here. The original header here will NEVER have anything new
  94.  inserted before this space, to maintain a somewhat compatible file. The
  95.  original header, described about will always be 869 bytes long+SongText
  96.  len. So you should seek up HdLen-(869+STLen) bytes after reading the header
  97.  in case there is more.
  98.  
  99.  
  100. Patterns
  101.  
  102. len      desc
  103. ----------------------------------------------------------------------------
  104.  1       Break location in the pattern (length in rows)
  105.  1       Tempo for this pattern. ** THIS VALUE IS *NOT* USED ANYMORE!!! ** DO
  106.            NOT SUPPORT IT!!
  107.  Rows*16*4  Pattern data-
  108.  
  109.  
  110.    len      desc
  111.    --------------------------------------------
  112.     1       Note value - (Octave*12+Note)+1 or 0 for no note
  113.     1       Instrument/sample value
  114.     1       Volume - reversed byte. MSN is stored as LSN, LSN as MSN. This is
  115.             for compatibility purposes. Basically, the lower nybble is the
  116.             major volume adjust, upper nybble for minor adjust.
  117.     1       Effect, upper nybble is effect, lower nybble is parameter
  118.  
  119. Current no provisions are made in this format to remove unused channels from
  120. the file.
  121.  
  122.  
  123.  
  124. Sample Map
  125.  
  126. This is an array of 0-7 (8 bytes) which is a set of 64 flags. Each flag
  127. corresponds to a sample, and these flags are packed into bytes. If the bit
  128. is set, the sample record IS stored in the file. Otherwise, it is not (and
  129. therefore should NOT be read). You can check to see if its present like this:
  130.  
  131. if (SMap[SampleNumber/8] & (1<<(SampleNumber%8))) ReadSample(SampleNumber);
  132.  
  133. Now that I think about it, I wonder why I didn't just store all the samples
  134. that are used up to the last used one? Who knows.. I was tired that night :)
  135.  
  136.  
  137.  
  138. Samples/records
  139.  
  140. All samples are stored just like they are in FSM format on disk. Each one is
  141. header-data-header-data, etc. Here is the header format:
  142.  
  143. len     desc
  144. ---------------------------------------------------------------------------
  145.  32     Name of sample
  146.  4      Length of sample (currently only support up to 64k samples)
  147.  1      Finetune (also not supported right now)
  148.  1      Volume ... yet another unsupported feature
  149.  4      Repeat Start
  150.  4      Repeat End - If the sample is looping, this should be set to the repeat
  151.         end value. Otherwise, it should be set to the length of the sample.
  152.  1      Sample Type byte
  153.  
  154.    1<<0   8/16 bit (8=0 16=1)
  155.  
  156.  1      Looping mode byte
  157.  
  158.    1<<3   On=looped, Off=not looped
  159.  
  160.  (len)  Sample data in SIGNED format
  161.  
  162.  
  163.  
  164.  
  165. Info on playing-
  166.  
  167. Here are how you generate the various FX:
  168.  
  169. FEKT           Hex#     How!
  170. ----------------------------------------------------------------------------
  171. Tempo          0xf?     Notes per second is 32/Tempo.
  172. Pitch Adjust   0x1?     Add ?*4 values to the value you're sending to the
  173.                         GUS. This is based on 16 channels. If you're using
  174.                         more or less, then you will have to calculate the
  175.                         pitch through this proportion:
  176.  
  177.                           x     ?
  178.                           -- = ---
  179.                           16   chn
  180.  
  181.                         which simplifies to
  182.  
  183.                         chn*x=16*?
  184.                         or
  185.                           16*?
  186.                         x=----
  187.                           chn
  188.  
  189.                         where ? is the amount, chn is the # of channels and
  190.                         x is the amount you add to the pitch value. Note that
  191.                         this effect and the one below are CUMULATIVE.
  192.  
  193. Pitch Adjust   0x2?     Do the same as above, except subtract from the val
  194. Fine Tempo up  0xe?     Add this number to the current interrupt calls per
  195.                         second. Sorry, I could not figure out any other way
  196.                         to do it. My tempos are based on a system of 128/Tempo
  197.                         for finer control of other things, so this value would
  198.                         be added to that number instead of 32/x. So again,
  199.                         solve the proportion.
  200. Fine Tempo dn  0xd?     Same as above, but subtract from tempo
  201. Fine Tempo cnl 0xe? or  Cancel fine tempo; revert ints/sec to normal value
  202.                0xd?     for current tempo
  203. Port to Note   0x3?     Slide from current pitch to the pitch specified on
  204.                         the line where the command is issued. The parameter
  205.                         tells in how many rows the pitch should have gotten
  206.                         to the destination. You can use this equation to
  207.                         figure a standard increment:
  208.  
  209.                               P
  210.                           ----------
  211.                           intSpeed*?
  212.  
  213.                         Where P is the pitch, intSpeed is the interrupt speed,
  214.                         and ? is the effect parameter. Of course an integer
  215.                         is not enough precision to store the increment most
  216.                         of the time.
  217. Retrigger      0x4?     Repeat the current note ? times in this bar. If a
  218.                         drum is issued as the note, and the parameter is 0x42
  219.                         then the drum should be played 2 times that bar, in
  220.                         evenly spaced intervals.
  221. Set VibDepth   0x5?     Set vibrato depth. Actually, in Farandole this value
  222.                         is used to generate a new sin table; perhaps not the
  223.                         most efficient way to do it, but what the hell.
  224.                         The table is generated using this equation:
  225.  
  226.                         f(x)=sin(2*pi*f*t)*a
  227.  
  228.                         ..where a is the value for the effect and f=1.
  229. Vibrato note   0x6?     Vibrato this note. Although it goes away if you stop
  230.                         using it, this effect when used repedeatly actually
  231.                         just tells FAR to continue the previous vibrato, which
  232.                         may span several notes depending on how large it is.
  233. Vibrato Sust   0x9?     Is the same as above, but it doesn't stop until you
  234.                         reach a 0x90 command
  235. VolSld Up      0x7?     Pushes the volume up one notch (0-F)
  236. VolSld Dn      0x8?     Same as above, but it goes down
  237. Port To Vol    0xA?     This uses the same method as the Port-To-Note command,
  238.                         but it acts on volume
  239. Note Offset    0xC?     Pretend that you're doing an F-Retrigger command (0x4F).
  240.                         What you do is blank out all the notes in the retrig
  241.                         except the one specified here.
  242.  
  243. * Info specific to above commands in Farandole: The way I handle it is like
  244. this: My interrupt is based around 128 times a second, so I generate a table
  245. where the x domain is 0..127. You then use the ? value from the 0x6 command
  246. to skip through the table, where the table increment is ?*6. You should keep
  247. looping through the table until the vibrato commands go away. See FARTRAK.CPP
  248. for more details.
  249.  
  250.  
  251. For more info, please see the sample code, FARTRAK.CPP (again, like FARLOAD.CPP
  252. this is code straight from the composer. So if there is descrepency, the code
  253. is correct, not this doc.)
  254.  
  255.  
  256.  
  257.                    Farandole .FSM Sample/instrument format
  258.                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  259.  
  260. Header
  261.  
  262. This format is almost identical to the one described above for samples in .FAR
  263. files. Note also that this format is set up like .FAR, where you can type
  264. out the file to see the long name for it.
  265.  
  266. len      desc
  267. ----------------------------------------------------------------------------
  268.  4       "FSM■" - File magic
  269.  32      Sample name
  270.  3       (10,13,26)
  271.  4      Length of sample (currently only support up to 64k samples)
  272.  1      Finetune (also not supported right now)
  273.  1      Volume ... yet another unsupported feature
  274.  4      Repeat Start
  275.  4      Repeat End - If the sample is looping, this should be set to the repeat
  276.         end value. Otherwise, it should be set to the length of the sample.
  277.  1      Sample Type byte
  278.  
  279.    1<<0   8/16 bit (8=0 16=1)
  280.  
  281.  1      Looping mode byte
  282.  
  283.    1<<3   On=looped, Off=not looped
  284.  
  285.  (len)  Sample data in SIGNED format
  286.  
  287.  
  288.  
  289.                   Farandole .USM Sample/instrument format
  290.                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  291.  
  292.  (len)  Sample data in UNSIGNED format
  293.  
  294.  
  295.  
  296.                        Farandole .FPT Pattern format
  297.                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  298.  
  299. len        desc
  300. ---------------------------------------------------------------------------
  301.  4         "FPT■" File magic
  302.  32        Pattern Name
  303.  3         (10,13,26)
  304.  2         PatStore array length (PatSize)(Total remaining length of file)
  305.  1         Break Location
  306.  1         Unused
  307.  PatSize-2 Pattern in raw format (just like in .FAR file)
  308.  
  309.  
  310.  
  311.                  Farandole .F2R Linear module (2.0) format
  312.                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  313.                              (file imported)
  314. ------------------------------------------------------------------------------
  315. F2R (Farandole Form2.0) linear-layout digital music specifications.
  316. By Daniel Potter/Digital Infinity.
  317.  
  318. This is the internal format we use for writing demos. Currently there are
  319. these versions of the F2R playing code:
  320.  
  321. A) A full C++ version that is rather slow, but plays all effects correctly.
  322. B) A full ASM version that is fast, although in real mode, and plays almost
  323.    no effects
  324. C) A full ASM version in protected mode that has been extremely optimized and
  325.    plays almost no effects (working on it).
  326.  
  327. These will all be available when I see that they are fit for the public eye..
  328.  
  329. You will see in a moment why I call it a linear-layout format. Everything can
  330. be read easily in one pass without mixing up too many variables. (Ex: sample
  331. data is stored with sample headers..)
  332.  
  333.  
  334. Header A
  335. --------
  336.  
  337. len           description
  338. ---           -----------
  339.  3            'F2R' - file magic
  340.  3            Composer magic. Only existing one right now is 'FAR' (farandole)
  341.  40           Song name in ASCIIZ
  342.  2            Songtext length (in bytes)
  343.  STLen        Songtext (length in previous field)
  344.  1            Song version. Current version is 0x20 (2.0)
  345.  1            Number of channels. Probly not more than 16, but up 256.
  346.  1            Default tempo, in ticks per second.
  347.  NChan        Default panning for each channel (length in NOC field above)
  348.  1            Number of samples saved in file.
  349.  
  350.  
  351. Sample Structures
  352. -----------------
  353.  
  354. len           description
  355. ---           -----------
  356. 32            Sample name in ASCIIZ
  357. 4             Sample length (PC dword)
  358. 1             FineTune. Not currently supported.
  359. 1             Volume. Also has no purpose currently.
  360. 4             Repeat START (PC dword)
  361. 4             Repeat END (PC dword) (note that this is NOT repeat LENGTH)
  362. 1             Sample type. bit 0=1->16 bit data
  363. Len           Sample data in signed format (length=SLen field above)
  364.  
  365. This structure repeats for the number of samples stored in the file.
  366.  
  367.  
  368. Header B
  369. --------
  370.  
  371. len           description
  372. ---           -----------
  373.  3            SectionID - 'JDC' - (see below comment)
  374.  1            Order length
  375.  1            Number of patterns stored in file
  376.  1            Loop To value (order index)
  377.  128          Order table. Blank entries padded with 0xFF
  378.  
  379.  
  380. Pattern Structure
  381. -----------------
  382.  
  383.  
  384. len           description
  385. ---           -----------
  386.  3            SectionID - 'JDC'
  387.  2            Number of events stored in this pattern
  388.  4            Length of pattern in bytes (starting with next byte)
  389.  
  390. What remains is an event for each thing that is to happen on any channel. This
  391. eliminates the need for saving blank data, and thus this is currently the
  392. most efficient digital format out. Here's the format of each event:
  393.  
  394. len           description
  395. ---           -----------
  396.  1            Event type. Each bit denotes a bit of information included:
  397.  
  398.       bit     description
  399.       ---     -----------
  400.        0      New note pitch
  401.        1      New instrument value
  402.        2      Start a new note
  403.        3      New volume
  404.        4      Effect (normal effect)
  405.        5      Extended effect
  406.  
  407.  1            Channel
  408.  
  409. Each of the follow is included only if the appropriate bit is set:
  410.  
  411.  1            ET0-(Octave*12)+Note
  412.  1            ET1-Sample number
  413.  1            ET3-Volume (0-FF)
  414.  2            ET4-effect #+effect data 1
  415.  1            ET5-effect data 2
  416.  
  417.  1            Eventtick - number of ticks to wait before processing next event
  418.  
  419. The above structure repeats for NumEvents (in pattern header) and the entire
  420. pattern structure continues until all patterns are saved.
  421.  
  422. Effects are standard Farandole Composer effects. Here is a list in case you
  423. do not know them:
  424.  
  425. 0- No effect
  426. 1- Slide pitch up
  427. 2- Slide pitch down
  428. 3- Slide to pitch *
  429. 4- Retrigger
  430. 5- Set vibrato amplitude
  431. 6- Vibrato current note with given wavelength
  432. 7- Volume slide up
  433. 8- Volume slide down
  434. 9- Sustained vibrato
  435. A- Slide to volume *
  436. B- Set panning
  437. C- Note offset
  438. D- Fine tempo down
  439. E- Fine tempo up
  440. F- Set tempo
  441.  
  442. *-extended effect (ET5)
  443.  
  444. For more info on how these work and how they are implemented, please see the
  445. Farandole documentation, FORMATS.DOC.
  446.  
  447. In the case of the extended effects, the second parameter is what is being
  448. slid to. ie pitch slide, parameter two is the pitch to slide to, and vol
  449. slide, is the volume to slide to.
  450.  
  451. Note about SectionID: I had a tremendous trouble debugging originally because
  452. since all the data in the file practically looked like garbage, there was no
  453. way to tell what was going on. What this does is provide the program a way to
  454. gauge if the file is valid. If you ever read a section ID and it is not 'JDC'
  455. verbatim you should stop reading the file and declare it invalid.
  456.  
  457. This format was provided as a service to the general demo/music/game community.
  458. It may be used for any purpose, however if you use my format I would like to
  459. at least be greeted or credited or something.. whatever you feel is appropriate.
  460.  
  461.  
  462.                                                            Good luck!
  463.                                                            Daniel Potter/DI
  464.                                                            Apr 13, 1994
  465. ----------------------------------------------------------------------------
  466.  
  467.                  
  468.